A propos

Cette documentation présentera en détail l’architecture fondamentale requise pour mettre en place la fédération de CO avec le protocole ActivityPub. Elle expliquera les différents composants nécessaires et sa mise en œuvre.

Composants

L’implémentation se trouve dans le module citizenToolKit, plus précisément dans le dossier components/activitypub. Elle utilise l’espace de noms PixelHumain\PixelHumain\modules\citizenToolKit\components\activitypub. Le dossier racine contient trois sous-dossiers ainsi qu’un fichier de configuration :

• /type : qui contient les classes représentant les différents types (vocabulaires) d’ActivityStream utilisés pour les activités dans ActivityPub
• /handlers : qui contient toutes les classes qui gèrent les flux "inbox/outbox"
• /utils : qui contient les classes et fonctions utilitaires
• config.php : qui contient la configuration de l’instance.

Type

Ce dossier contient les mises en œuvre de tous les types recommandés dans Activitystream 2.0 vocabulary, classés selon lecore type et le extend type. La figure ci-dessous montre le diagramme de classe de types qu’on a implémenté:

.

Handlers

Ce dossier contient les classes qui gèrent les activités entrantes et sortantes de la fédération. Il y a une classe commune pour la gestion des événements appelée "Handler.php". Cette classe distribue les activités et appelle automatiquement la classe "handler" qui est responsable de l’activité en cours. Pour cela, la classe "handler" doit suivre les règles suivantes :

1. Elle doit être située dans le dossier handlers/activity. Par exemple, si on veut gérer les activités de type create, il faut placer le handler dans handlers/create.
2. Le nom de la classe handler doit être comme suit : ActivityObjectHandler, c’est-à-dire la concaténation du type d’activité, du type d’objet et du mot Handler. Par exemple, si on veut gérer l’activité de création d’une note, il faut créer une classe qui s’appelle CreateNoteHandler.
3. La classe handler doit hériter de la classe abstraite AbstractHandler et doit implémenter les deux méthodes suivantes :
   • handleActivityFromClient : appelé lorqu’un utilisateur dans CO envoye un activité (en effet il faut faire la féderation)
   • handleActivityFromServer : appelé lorqu’on reçoit un activité venant des autres instances. La figure ci-dessous montre le diagramme de classe de la gestion des activités:

Utils

Ce dossier contient uniquement les classes utilitaires nécessaires à notre application, notamment :

• HttpSignature : cette classe permet de signer les activités à fédérer et de vérifier la signature des activités entrantes. Voir ici pour plus de details sur (HTTP Signatures)
• Request : cette classe permet simplement de faire des requêtes HTTP et gère automatiquement la signature des données à envoyer.

Config.php

Ce fichier contient juste la configuration HOSTNAME de notre instance.

Structure de données

Pour faire fonctionner ActivityPub, nous avons créé trois nouvelles collections :

• activitypub_activity
• activitypub_object
• et activitypub_cron

La collection activitypub_activity

Il s’agit d’une collection qui permet de stocker les différents flux d’activités. Elle comporte quatre entrées :

• uuid : une chaîne de caractères qui sert d’identifiant unique pour chaque enregistrement
• from : une chaîne de caractères indiquant le lien de la ressource à l’origine de l’activité
• to : un tableau de chaînes de caractères contenant la liste des destinataires de l’activité
• activity : un objet Activity Stream qui renferme les détails de l’activité.

La collection activitypub_object

Cette collection ne contient que les objets des activités fédérées par d’autres plateformes. Elle sert de cache pour garantir que les objets seront toujours disponibles même si l’instance source est indisponible. Elle se compose de seulement deux entrées, à savoir :

• UUID : un identifiant unique ;
• Object : un objet de flux d’activités.

La collection activitypub_cron

Cette collection permet d’enregistrer les activités des utilisateurs locaux afin de les envoyer ultérieurement via une tâche cron. Cela permet d’éviter aux utilisateurs d’attendre le processus de fédération. La collection contient 5 entrées :

• sender : une chaîne de caractères représentant l’expéditeur
• receiver : une chaîne de caractères représentant le destinataire
• data : un objet activitystream à envoyer
• nbAttempt : le nombre de tentatives d’envoi
• status : l’état de l’envoi, "fail" ou "done".

Mis en oeuvre

Webfinger

La première étape consiste à résoudre une ressource de type user@domain en utilisant l’endpoint /.well-known/webfinger?resource=slug@domain. Cela devrait renvoyer le webfinger de la ressource demandé. Pour notre cas, l’alias /.well-known/webfinger?resource=slug@domain est redirigé vers /api/activitypub/webfinger. On a utilise PixelHumain\PixelHumain\modules\api\controllers\ActivitypubController comme controlleur et \PixelHumain\PixelHumain\modules\api\controllers\activitypub\WebfingerAction comme action. Le WebFinger doit renvoyer un lien qui permet de récupérer les informations relatives à la ressource en question. Cela nécessite la création d’un point d’accès qui renvoie les informations de cette ressource. Dans notre cas, cet point d’accès est /api/activitypub/users/u/slug. On utilise l’action \PixelHumain\PixelHumain\modules\api\controllers\activitypub\GetActorAction.

Configuration de la redirection

Pour qu’on puisse faire la redirection de /.well-known/webfinger?resource=slug@domain vers /api/activitypub/webfinger il faut qu’on fasse une réecriture d’url dans .htaccess.

RewriteEngine On

RewriteCond %{REQUEST_URI}  /\.well-known/webfinger$
RewriteCond %{QUERY_STRING} resource=([^&]+)
RewriteRule ^(.*)$ /wf/%1.json [L]

RewriteRule ^/.well-known/webfinger$ - [L,R=400]

Remarque: Pour obtenir le format JSON pour chaque ressource demandée, il est nécessaire d’ajouter .json à la fin de l’URL. Par exemple, pour accéder à la ressource /api/activitypub/users/u/slug, il faudrait faire /api/activitypub/users/u/slug.json

WebfingerAction

Pour générer le WebFinger d’une ressource, il suffit d’utiliser la classe WebFinger pour l’analyser et le créer renvoyer le PixelHumain\PixelHumain\modules\citizenToolKit\components\activitypub\handlers\Webfinger qui correspond à la ressource demandé.

Inbox

L’« inbox » le point d’entré à notre instance, il est accèssible via /api/activitypub/inbox/u/slug, et l’action correspondante est le PixelHumain\PixelHumain\modules\api\controllers\activitypub\InboxAction. Lorsqu’une activité est reçue, la méthode PixelHumain\PixelHumain\modules\citizenToolKit\components\activitypub\type\Type::create est appelée dans l’« InboxAction » pour créer une instance du type correspondant. Ensuite, la méthode PixelHumain\PixelHumain\modules\citizenToolKit\components\activitypub\handlers\Handler::handle est utilisée pour dispatcher l’activité vers le gestionnaire qui lui correspond.

Outbox

…